When you work with neuroimaging, it is useful to be able to explore the images in a viewer. There are many great viewers, like MRIcroGL, ITK-SNAP or Mango, just to name a few. However if your images are on a remote server with no or limited desktop access, you cannot directly use these softwares. You will first have to download the images locally.
Additionally, it’s difficult to share a specific view of an images stack, such as an overlay of specific layers with specific thresholds, color tables and transparency.
Fortunately a few years ago John Muschelli made a widget for the Papaya JS viewer, which allows to programmatically define all the aspects of the intended visualization (hereafter, viz).
What is really great is that when this papaya widget is used within an Rmarkdown notebook, the produced html page is self-contained and can be shared with anybody else. It contains one (or mode) full-fledged image browser in which you can then change color maps, thresholds, and even load new images.
One of the very few limitations of the papayawidget is that if the
code in the rendered HMTL is displayed, some tools of the papaya browser
are not shown in the correct location. For this reason all the code is
here hidden and can be reviewed either by expanding it (click on the top
right button) or in the source .Rmd file.
This should however not represent a big problem, since the primary use of this tool should be to share HTML pages with the image browser for interactive exploration, rather than the code that generates them.
To use the papayawidget you
will need to have the devtools library and a nifti image
loaded - in this case I chose RNifti. Of course you
also need to install the widget.
Below is the code to load these libraries and - commented - the code to install them if you don’t have it yet.
# Libs and bd_results
# install.packages("devtools")
library(devtools)
# install.packages("papayaWidget")
# devtools::install_github("muschellij2/papayaWidget")
library(papayaWidget)
# remotes::install_github("jonclayden/RNifti")
library(RNifti)
# papaya widget github : https://github.com/muschellij2/papayaWidget
# app code here: https://github.com/muschellij2/linked_viewer/blob/master/app.R
bd_results = "/data00/leonardo/oda/GUTS_fmri_preproc/TUT/02_papaya"To show how to use the papaya widget, we will use some tissue maps of the average MNI152 taken from the FSL data/standard directory.
We will simply overlay them on top of the MNI to show their location. Note that I will also use a “Dummy” image which is simply an empty image. I will load this first since papaya does not allow to change the transparency on the image you load first - usually an anatomical / T1w image - while we can imagine situations in which we would like to do so.
In the basic example we will just load the images with only one option for the colormap. The syntax is pretty straightforward:
Once you are done editing the code, click on the Knit button just on
top of the editor to generate the HTML page - or use
CMD-Shift-K (Mac) or Ctrl-Shift-K
(Windoze)
Once the images are loaded, you can click on the squares on the top right corresponding to each loaded image. This will allow you to modify colormap, alpha (transparency) and thresholds.
Another small limitation of the widget is that the name of the image is not shown in the viewer, unfortunately.
A quick-and-dirty remedy to this is to provide a legend here in the markdown section of the notebook:
Color legend
papaya(
c(Dummy, MNI, GM, WM, CSF),
option = list(
papayaOptions(lut = "Grayscale"),
papayaOptions(lut = "Grayscale"),
papayaOptions(lut = "Red Overlay"),
papayaOptions(lut = "Blue Overlay"),
papayaOptions(lut = "Green Overlay")
),
interpolation = FALSE
)You can also decide to show the images with a given threshold and
transparency (alpha). Check out ?papayaOptions for the
complete list of options
Color legend
papaya(
c(Dummy, MNI, GM, WM, CSF),
option = list(
papayaOptions(alpha = 1, lut = "Grayscale"),
papayaOptions(alpha = 1, lut = "Grayscale"),
papayaOptions(alpha = 0.7, lut = "Red Overlay", min = 0.4, max = 1),
papayaOptions(alpha = 0.7, lut = "Blue Overlay", min = 0.4, max = 1),
papayaOptions(alpha = 0.7, lut = "Green Overlay", min = 0.4, max = 1)
),
interpolation = FALSE
)